home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 4: GNU Archives / Linux Cubed Series 4 - GNU Archives.iso / gnu / automake.0 / automake / automake-1.0 / automake.info < prev    next >
Encoding:
GNU Info File  |  1996-05-29  |  57.0 KB  |  1,563 lines
  1. This is Info file ./automake.info, produced by Makeinfo-1.55 from the
  2. input file automake.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * automake: (automake).        Making Makefile.in's
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents GNU automake 1.0
  9.  
  10.    Copyright (C) 1995 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26. 
  27. File: automake.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  28.  
  29. GNU Automake
  30. ************
  31.  
  32.    This file documents the GNU Automake package for creating GNU
  33. Standards-compliant Makefiles from template files.  This edition
  34. documents version 1.0.
  35.  
  36. * Menu:
  37.  
  38. * Introduction::                Automake's purpose
  39. * Invoking Automake::           Creating a Makefile.in
  40. * Generalities::                General ideas
  41. * configure::                   Scanning configure.in
  42. * Top level::                   The top-level Makefile.am
  43. * Programs::                    Building programs and libraries
  44. * Other objects::               Other derived objects
  45. * Documentation::               Building documentation
  46. * Install::                     What gets installed
  47. * Clean::                       What gets cleaned
  48. * Dist::                        What goes in a distribution
  49. * Tests::                       Support for test suites
  50. * Options::                     Changing Automake's behavior
  51. * Miscellaneous::               Miscellaneous rules
  52. * Extending::                   Extending Automake
  53. * Distributing::                Distributing the Makefile.in
  54. * Examples::                    Some example packages
  55. * Future::                      Some ideas for the future
  56. * Variables::                   Index of variables
  57. * Configure variables::         Index of configure variables and macros
  58. * Targets::                     Index of targets
  59.  
  60. 
  61. File: automake.info,  Node: Introduction,  Next: Invoking Automake,  Prev: Top,  Up: Top
  62.  
  63. Introduction
  64. ************
  65.  
  66.    Automake is a tool for automatically generating `Makefile.in's from
  67. files called `Makefile.am'.  The `Makefile.am' is basically a series of
  68. `make' macro definitions (with rules being thrown in occasionally).
  69. The generated `Makefile.in's are compliant with the GNU Makefile
  70. standards.
  71.  
  72.    The GNU Makefile Standards Document (*note Makefile Conventions:
  73. (standards.info)Makefile Conventions.) is long, complicated, and
  74. subject to change.  The goal of Automake is to remove the burden of
  75. Makefile maintenance from the back of the individual GNU maintainer
  76. (and put it on the back of the Automake maintainer).
  77.  
  78.    The typical Automake input files is simply a series of macro
  79. definitions.  Each such file is processed to create a `Makefile.in'.
  80. There should generally be one `Makefile.am' per directory of a project.
  81.  
  82.    Automake does constrain a project in certain ways; for instance it
  83. assumes that the project uses Autoconf (*note The Autoconf Manual:
  84. (autoconf.info)Top.), and enforces certain restrictions on the
  85. `configure.in' contents.
  86.  
  87.    `Automake' requires `perl' in order to generate the `Makefile.in's.
  88. However, the distributions created by Automake are fully GNU
  89. standards-compliant, and do not require `perl' in order to be built.
  90.  
  91.    Mail suggestions and bug reports for Automake to tromey@cygnus.com.
  92.  
  93. 
  94. File: automake.info,  Node: Invoking Automake,  Next: Generalities,  Prev: Introduction,  Up: Top
  95.  
  96. Creating a `Makefile.in'
  97. ************************
  98.  
  99.    To create all the `Makefile.in's for a package, run the `automake'
  100. program in the top level directory, with no arguments.  `automake' will
  101. automatically find each appropriate `Makefile.am' (by scanning
  102. `configure.in'; *note configure::.) and generate the corresponding
  103. `Makefile.in'.
  104.  
  105.    You can optionally give `automake' an argument; `.am' is appended to
  106. the argument and the result is used as the name of the input file.
  107. This feature is generally only used to automatically rebuild an
  108. out-of-date `Makefile.in'.  Note that `automake' must always be run
  109. from the topmost directory of a project, even if being used to
  110. regenerate the `Makefile.in' in some subdirectory.  This is necessary
  111. because `automake' must scan `configure.in', and because `automake'
  112. uses the knowledge that a `Makefile.in' is in a subdirectory to change
  113. its behavior in some cases.
  114.  
  115.    `automake' accepts the following options:
  116.  
  117. `--amdir=DIR'
  118.      Look for Automake data files in directory DIR instead of in the
  119.      installation directory.  This is typically used for debugging.
  120.  
  121. `--foreign'
  122.      An alias for `--strictness=foreign'.
  123.  
  124. `--gnits'
  125.      An alias for `--strictness=gnits'.
  126.  
  127. `--gnu'
  128.      An alias for `--strictness=gnu'.
  129.  
  130. `--help'
  131.      Print a summary of the command line options and exit.
  132.  
  133. `--include-deps'
  134.      Include all automatically generated dependency information (*note
  135.      Dependencies::.) in the generated `Makefile.in'.  This is
  136.      generally done when making a distribution; see *Note Dist::.
  137.  
  138. `--add-missing'
  139.      Automake requires certain common files to exist in certain
  140.      situations; for instance `config.guess' is required if
  141.      `configure.in' runs `AC_CANONICAL_HOST'.  Automake is distributed
  142.      with several of these files; this option will cause the missing
  143.      ones to be automatically added to the package, whenever possible.
  144.  
  145. `--output-dir=DIR'
  146.      Put the generated `Makefile.in' in the directory DIR.  Ordinarily
  147.      each `Makefile.in' is created in the directory of the
  148.      corresponding `Makefile.am'.  This option is used when making
  149.      distributions.
  150.  
  151. `--strictness=LEVEL'
  152.      Set the global strictness to LEVEL; this can be overridden in each
  153.      `Makefile.am' if required.  *Note Generalities:: for more
  154.      information.
  155.  
  156. `--verbose'
  157.      Cause Automake to print information about which files are being
  158.      read or created.
  159.  
  160. `--version'
  161.      Print the version number of Automake and exit.
  162.  
  163. 
  164. File: automake.info,  Node: Generalities,  Next: configure,  Prev: Invoking Automake,  Up: Top
  165.  
  166. General ideas
  167. *************
  168.  
  169. Depth
  170. =====
  171.  
  172.    `automake' supports three kinds of directory hierarchy: "flat",
  173. "shallow", and "deep".
  174.  
  175.    A "flat" package is one in which all the files are in a single
  176. directory.  The `Makefile.am' for such a package by definition lacks a
  177. `SUBDIRS' macro.  An example of such a package is `termutils'.
  178.  
  179.    A "deep" package is one in which all the source lies in
  180. subdirectories; the top level directory contains mainly configuration
  181. information.  GNU cpio is a good example of such a package, as is GNU
  182. `tar'.  The top level `Makefile.am' for a deep package will contain a
  183. `SUBDIRS' macro, but no other macros to define objects which are built.
  184.  
  185.    A "shallow" package is one in which the primary source resides in
  186. the top-level directory, while various parts (typically libraries)
  187. reside in subdirectories.  `automake' is one such package (as is GNU
  188. `make', which does not currently use `automake').
  189.  
  190. Strictness
  191. ==========
  192.  
  193.    While Automake is intended to be used by maintainers of GNU
  194. packages, it does make some effort to accomodate those who wish to use
  195. it, but do not want to use all the GNU conventions.
  196.  
  197.    To this end, Automake supports three levels of "strictness" - the
  198. strictness indicating how stringently Automake should check standards
  199. conformance.
  200.  
  201.    The valid strictness levels are:
  202.  
  203. `foreign'
  204.      Automake will check for only those things which are absolutely
  205.      required for proper operations.  For instance, whereas GNU
  206.      standards dictate the existence of a `NEWS' file, it will not be
  207.      required in this mode.  The name comes from the fact that Automake
  208.      is intended to be used for GNU programs; these relaxed rules are
  209.      not the standard mode of operation.
  210.  
  211. `gnu'
  212.      Automake will check - as much as possible - for compliance to the
  213.      GNU standards for packages.  This is the default.
  214.  
  215. `gnits'
  216.      Automake will check for compliance to the as-yet-unwritten GNITS
  217.      standards.  These are based on the GNU standards, but are even more
  218.      detailed.  Unless you are a GNITS standards contributor, it is
  219.      recommended that you avoid this option until such time as the GNITS
  220.      standard is actually published.
  221.  
  222. The Uniform Naming Scheme
  223. =========================
  224.  
  225.    Automake variables generally follow a uniform naming scheme that
  226. makes it easy to decide how programs (and other derived objects) are
  227. built, and how they are installed.  This scheme also supports
  228. `configure' time determination of what should be built.
  229.  
  230.    At `make' time, certain variables are used to determine which
  231. objects are to be built.  These variables are called "primary"
  232. variables.  For instance, the primary variable `PROGRAMS' holds a list
  233. of programs which are to be compiled and linked.
  234.  
  235.    A different set of variables is used to decide where the built
  236. objects should be installed.  These variables are named after the
  237. primary variables, but have a prefix indicating which standard
  238. directory should be used as the installation directory.  The standard
  239. directory names are given in the GNU standards (*note Directory
  240. Variables: (standards.info)Directory Variables.).  `automake' extends
  241. this list with `pkglibdir', `pkgincludedir', and `pkgdatadir'; these
  242. are the same as the non-`pkg' versions, but with `@PACKAGE@' appended.
  243.  
  244.    For each primary, there is one additional variable named by
  245. prepending `EXTRA_' to the primary name.  This variable is used to list
  246. objects which may or may not be built, depending on what `configure'
  247. decides.  This variable is required because Automake must know the
  248. entire list of objects to be built in order to generate a `Makefile.in'
  249. that will work in all cases.
  250.  
  251.    For instance, `cpio' decides at configure time which programs are
  252. built.  Some of the programs are installed in `bindir', and some are
  253. installed in `sbindir':
  254.  
  255.      EXTRA_PROGRAMS = mt rmt
  256.      bin_PROGRAMS = cpio pax
  257.      sbin_PROGRAMS = @PROGRAMS@
  258.  
  259.    Defining a primary variable is an error.
  260.  
  261.    Note that the common `dir' suffix is left off when constructing the
  262. variable names; thus one writes `bin_PROGRAMS' and not
  263. `bindir_PROGRAMS'.
  264.  
  265.    Not every sort of object can be installed in every directory.
  266. Automake will flag those attempts it finds in error.  Automake will
  267. also diagnose obvious misspellings in directory names.
  268.  
  269.    Sometimes the standard directories - even as augmented by Automake -
  270. are not enough.  In particular it is sometimes useful, for clarity, to
  271. install objects in a subdirectory of some predefined directory.  To this
  272. end, Automake allows you to extend the list of possible installation
  273. directories.  A given prefix (eg `zar') is valid if a variable of the
  274. same name with `dir' appended is defined (eg `zardir').
  275.  
  276.    For instance, until HTML support is part of Automake, you could use
  277. this to install raw HTML documentation:
  278.  
  279.      htmldir = $(prefix)/html
  280.      html_DATA = automake.html
  281.  
  282.    The special prefix `noinst' indicates that the objects in question
  283. should not be installed at all.
  284.  
  285.    The special prefix `check' indicates that the objects in question
  286. should not be built until the `make check' command is run.
  287.  
  288.    Possible primary names are `PROGRAMS', `LIBRARIES', `SCRIPTS',
  289. `DATA', `HEADERS', `MANS', and `TEXINFOS'.
  290.  
  291. General Operation
  292. =================
  293.  
  294.    Automake essentially works by reading a `Makefile.am' and generating
  295. a `Makefile.in'.  The macro definitions and targets in the
  296. `Makefile.am' are copied into the generated file.
  297.  
  298.    Automake tries to group comments with adjoining targets (or variable
  299. definitions) in an intelligent way.
  300.  
  301.    A target defined in `Makefile.am' generally overrides any such
  302. target of a similar name that would be automatically generated by
  303. `automake'.  Although this is a supported feature, it is generally best
  304. to avoid making use of it, as sometimes the generated rules are very
  305. particular.
  306.  
  307.    Automake also allows a form of comment which is *not* copied into
  308. the output; all lines beginning with `##' are completely ignored by
  309. Automake.
  310.  
  311.    It is customary to make the first line of `Makefile.am' read:
  312.  
  313.      ## Process this file with automake to produce Makefile.in
  314.  
  315. 
  316. File: automake.info,  Node: configure,  Next: Top level,  Prev: Generalities,  Up: Top
  317.  
  318. Scanning `configure.in'
  319. ***********************
  320.  
  321.    Automake requires certain variables to be defined and certain macros
  322. to be used in the package `configure.in'.
  323.  
  324.    One such requirement is that `configure.in' must define the
  325. variables `PACKAGE' and `VERSION' with `AC_SUBST'.  `PACKAGE' should be
  326. the name of the package as it appears when bundled for distribution.
  327. For instance, Automake definees `PACKAGE' to be `automake'.  `VERSION'
  328. should be the version number of the release that is being developed.
  329. We recommend that you make `configure.in' the only place in your
  330. package where the version number is defined; this makes releases
  331. simpler.
  332.  
  333.    Automake requires the use of the macro `AC_ARG_PROGRAM' if a program
  334. or script is installed.
  335.  
  336.    If your package is not a flat distribution, Automake requires the
  337. use of `AC_PROG_MAKE_SET'.
  338.  
  339.    Automake will also recognize the use of certain macros and tailor the
  340. generated `Makefile.in' appropriately.  Currently recognized macros and
  341. their effects are:
  342.  
  343. `AC_CONFIG_HEADER'
  344.      Automake will generate rules to automatically regenerate the config
  345.      header.  If you do use this macro, you must create the file
  346.      `stamp-h.in'.  It can be empty.  Also, the `AC_OUTPUT' command in
  347.      `configure.in' must create `stamp-h', eg:
  348.           AC_OUTPUT(Makefile, [test -z "$CONFIG_HEADERS" || echo timestamp > stamp-h])
  349.  
  350. `AC_CONFIG_AUX_DIR'
  351.      Automake will look for various helper scripts, such as
  352.      `mkinstalldirs', in the directory named in this macro invocation.
  353.      If not seen, the scripts are looked for in their "standard"
  354.      locations (either the top source directory, or in the source
  355.      directory corresponding to the current `Makefile.am', whichever is
  356.      appropriate).
  357.  
  358. `AC_OUTPUT'
  359.      Automake uses this to determine which files to create.
  360.  
  361. `AC_PATH_XTRA'
  362.      Automake will insert definitions for the variables defined by
  363.      `AC_PATH_XTRA' into each `Makefile.in' that builds a C program or
  364.      library.
  365.  
  366. `AC_CANONICAL_HOST'
  367. `AC_CANONICAL_SYSTEM'
  368. `AC_CHECK_TOOL'
  369.      Automake will ensure that `config.guess' and `config.sub' exist.
  370.  
  371. `AC_FUNC_ALLOCA'
  372. `AC_FUNC_GETLOADAVG'
  373. `AC_FUNC_MEMCMP'
  374. `AC_STRUCT_ST_BLOCKS'
  375. `fp_FUNC_FNMATCH'
  376. `AC_FUNC_FNMATCH'
  377. `AC_REPLACE_FUNCS'
  378. `AC_REPLACE_GNU_GETOPT'
  379.      Automake will ensure that the appropriate source files are part of
  380.      the distribution, and will ensure that the appropriate
  381.      dependencies are generated for these objects.  *Note A Library::
  382.      for more information.
  383.  
  384.      Automake will also detect statements which put `.o' files into
  385.      `LIBOBJS', and will treat these additional files in a similar way.
  386.  
  387. `AC_PROG_RANLIB'
  388.      This is required if any libraries are built in the package.
  389.  
  390. `AC_PROG_INSTALL'
  391. `fp_PROG_INSTALL'
  392.      `fp_PROG_INSTALL' is required if any scripts (*note Scripts::.) are
  393.      installed by the package.  Otherwise, `AC_PROG_INSTALL' is
  394.      required.
  395.  
  396. `gm_PROG_LIBTOOL'
  397. `AC_PROG_LIBTOOL'
  398.      Automake will turn on processing for `libtool' (*note The Libtool
  399.      Manual: (libtool.info)Top.).  This work is still preliminary.
  400.  
  401. `ALL_LINGUAS'
  402.      If Automake sees that this variable is set in `configure.in', it
  403.      will check the `po' directory to ensure that all the named `.po'
  404.      files exist, and that all the `.po' files that exist are named.
  405.  
  406. `fp_C_PROTOTYPES'
  407.      This is required when using automatic de-ANSI-fication, see *Note
  408.      ANSI::.
  409.  
  410. `ud_GNU_GETTEXT'
  411.      This macro is required for packages which use GNU gettext (FIXME
  412.      xref).  It is distributed with gettext.  Automake uses this macro
  413.      to ensure that the package meets some of gettext's requirements.
  414.  
  415. `jm_MAINTAINER_MODE'
  416.      This macro adds a `--enable-maintainer-mode' option to
  417.      `configure'.  If this is used, `automake' will cause
  418.      "maintainer-only" rules to be turned off by default in the
  419.      generated `Makefile.in's.
  420.  
  421.    The `fp_' macros are from Franc,ois Pinard and the `jm_' macro is
  422. from Jim Meyering.  Both sets are included with Automake.  `automake'
  423. will tell where the macros can be found if they are missing.
  424.  
  425. 
  426. File: automake.info,  Node: Top level,  Next: Programs,  Prev: configure,  Up: Top
  427.  
  428. The top-level `Makefile.am'
  429. ***************************
  430.  
  431.    In non-flat packages, the top level `Makefile.am' must tell Automake
  432. which subdirectories are to be built.  This is done via the `SUBDIRS'
  433. variable.
  434.  
  435.    The `SUBDIRS' macro holds a list of subdirectories in which building
  436. of various sorts can occur.  Many targets (eg `all') in the generated
  437. `Makefile' will run both locally and in all specified subdirectories.
  438. Note that the directories listed in `SUBDIRS' are not required to
  439. contain `Makefile.am's; only `Makefile's (after configuration).  This
  440. allows inclusion of libraries from packages which do not use Automake
  441. (such as `gettext').
  442.  
  443.    In a deep package, the top-level `Makefile.am' is often very short.
  444. For instance, here is the `Makefile.am' from the textutils distribution:
  445.  
  446.      SUBDIRS = lib src doc man
  447.      EXTRA_DIST = @README_ALPHA@
  448.  
  449.    `SUBDIRS' can contain configure substitutions (eg `@DIRS@');
  450. Automake itself does not actually examine the contents of this variable.
  451.  
  452.    If `SUBDIRS' is defined, then your `configure.in' must include
  453. `AC_PROG_MAKE_SET'.
  454.  
  455. 
  456. File: automake.info,  Node: Programs,  Next: Other objects,  Prev: Top level,  Up: Top
  457.  
  458. Building Programs and Libraries
  459. *******************************
  460.  
  461.    A large part of Automake's functionality is dedicated to making it
  462. easy to build C programs and libraries.
  463.  
  464. * Menu:
  465.  
  466. * A Program::                   Building a program
  467. * A Library::                   Building a library
  468. * ANSI::                        Automatic de-ANSI-fication
  469. * Dependencies::                Automatic dependency tracking
  470.  
  471. 
  472. File: automake.info,  Node: A Program,  Next: A Library,  Up: Programs
  473.  
  474. Building a program
  475. ==================
  476.  
  477.    In a directory containing source that gets built into a program (as
  478. opposed to a library), the `PROGRAMS' primary is used.  Programs can be
  479. installed in `bindir', `sbindir', `libexecdir', `pkglibdir', or not at
  480. all.
  481.  
  482.    For instance:
  483.  
  484.      bin_PROGRAMS = hello
  485.  
  486.    In this simple case, the resulting `Makefile.in' will contain code
  487. to generate a program named `hello'.  The variable `hello_SOURCES' is
  488. used to specify which source files get built into an executable:
  489.  
  490.      hello_SOURCES = hello.c
  491.  
  492.    This causes `hello.c' to be compiled into `hello.o', and then linked
  493. to produce `hello'.
  494.  
  495.    If `prog_SOURCES' is needed, but not specified, then it defaults to
  496. the single file `prog.c'.  Id est in the example above, the definition
  497. of `hello_SOURCES' is actually redundant.
  498.  
  499.    Multiple programs can be built in a single directory.  Multiple
  500. programs can share a single source file.  The source file must be
  501. listed in each `_SOURCES' definition.
  502.  
  503.    Header files listed in a `_SOURCES' definition will be ignored.  Lex
  504. (`.l') and yacc (`.y') files can also be listed; support for these
  505. should work but is still preliminary.
  506.  
  507.    Sometimes it is useful to determine the programs that are to be
  508. built at configure time.  For instance, GNU `cpio' only builts `mt' and
  509. `rmt' under special circumstances.
  510.  
  511.    In this case, you must notify `Automake' of all the programs that
  512. can possibly be built, but at the same time cause the generated
  513. `Makefile.in' to use the programs specified by `configure'.  This is
  514. done by having `configure' substitute values into each `_PROGRAMS'
  515. definition, while listing all optionally built programs in
  516. `EXTRA_PROGRAMS'.
  517.  
  518.    If you need to link against libraries that are not found by
  519. `configure', you can use `LDADD' to do so.  This variable actually can
  520. be used to add any options to the linker command line.
  521.  
  522.    Sometimes, multiple programs are built in one directory but do not
  523. share the same link-time requirements.  In this case, you can use the
  524. `PROG_LDADD' variable (where PROG is the name of the program as it
  525. appears in some `_PROGRAMS' variable, and usually written in lowercase)
  526. to override the global `LDADD'.  (If this variable exists for a given
  527. program, then that program is not linked using `LDADD'.)
  528.  
  529.    For instance, in GNU cpio, `pax', `cpio', and `mt' are linked
  530. against the library `libcpio.a'.  However, `rmt' is built in the same
  531. directory, and has no such link requirement.  Also, `mt' and `rmt' are
  532. only built on certain architectures.  Here is what cpio's
  533. `src/Makefile.am' looks like (abridged):
  534.  
  535.      bin_PROGRAMS = cpio pax @MT@
  536.      libexec_PROGRAMS = @RMT@
  537.      EXTRA_PROGRAMS = mt rmt
  538.      
  539.      LDADD = ../lib/libcpio.a @INTLLIBS@
  540.      rmt_LDADD =
  541.      
  542.      cpio_SOURCES = ...
  543.      pax_SOURCES = ...
  544.      mt_SOURCES = ...
  545.      rmt_SOURCES = ...
  546.  
  547.    It is also occasionally useful to have a program depend on some other
  548. target which is not actually part of that program.  This can be done
  549. using the `prog_DEPENDENCIES' variable.  Each program depends on the
  550. contents of such a variable, but no further interpretation is done.
  551.  
  552.    Since program names are rewritten into Makefile macro names, program
  553. names must follow Makefile macro syntax.  Sometimes it is useful to have
  554. a program whose name does not follow such rules.  In these cases,
  555. Automake canonicalizes the program name.  All characters in the name
  556. except for letters, numbers, and the underscore are turned into
  557. underscores when making macro references.  Eg, if your program is named
  558. `sniff-glue', you would use `sniff_glue_SOURCES', not
  559. `sniff-glue_SOURCES'.
  560.  
  561. 
  562. File: automake.info,  Node: A Library,  Next: ANSI,  Prev: A Program,  Up: Programs
  563.  
  564. Building a library
  565. ==================
  566.  
  567.    Building a library is much like building a program.  In this case,
  568. the name of the primary is `LIBRARIES'.  Libraries can be installed in
  569. `libdir' or `pkglibdir'.
  570.  
  571.    Each `_LIBRARIES' variable is a list of the base names of libraries
  572. to be built.  For instance to create a library named `libcpio.a', but
  573. not install it, you would write:
  574.  
  575.      noinst_LIBRARIES = cpio
  576.  
  577.    The sources that go into a library are determined exactly as they are
  578. for programs, via the `_SOURCES' variables.  Note that programs and
  579. libraries share a namespace, so one cannot have a program (`lob') and a
  580. library (`liblob.a') with the same name in one directory.
  581.  
  582.    Extra objects can be added to a library using the `library_LIBADD'
  583. variable.  This should be used for objects determined by `configure'.
  584. Again from cpio:
  585.  
  586.      cpio_LIBADD = @LIBOBJS@ @ALLOCA@
  587.  
  588.    Note that Automake explicitly recognizes the use of `@LIBOBJS@' and
  589. `@ALLOCA@' in the above example, and uses this information, plus the
  590. list of `LIBOBJS' files derived from `configure.in' to automatically
  591. include the appropriate source files in the distribution (*note
  592. Dist::.).  These source files are also automatically handled in the
  593. dependency-tracking scheme, see *Note Dependencies::.
  594.  
  595. 
  596. File: automake.info,  Node: ANSI,  Next: Dependencies,  Prev: A Library,  Up: Programs
  597.  
  598. Automatic de-ANSI-fication
  599. ==========================
  600.  
  601.    Although the GNU standards prohibit it, some GNU programs are
  602. written in ANSI C; see FIXME.  This is possible because each source
  603. file can be "de-ANSI-fied" before the actual compilation takes place.
  604.  
  605.    If the `Makefile.am' variable `AUTOMAKE_OPTIONS' (*Note Options::)
  606. contains the option `ansi2knr' then code to handle de-ANSI-fication is
  607. inserted into the generated `Makefile.in'.
  608.  
  609.    This causes each source file to be treated as ANSI C.  If an ANSI C
  610. compiler is available, it is used.
  611.  
  612.    This support requires the source files `ansi2knr.c' and `ansi2knr.1'
  613. to be in the same directory as the ANSI C source; these files are
  614. distributed with Automake.  Also, the package `configure.in' must call
  615. the macro `fp_C_PROTOTYPES'.
  616.  
  617. 
  618. File: automake.info,  Node: Dependencies,  Prev: ANSI,  Up: Programs
  619.  
  620. Automatic dependency tracking
  621. =============================
  622.  
  623.    As a developer it is often painful to continually update the
  624. `Makefile.in' whenever the include-file dependencies change in a
  625. project.  `automake' supplies a way to automatically track dependency
  626. changes, and distribute the dependencies in the generated `Makefile.in'.
  627.  
  628.    Currently this support requires the use of GNU `make' and `gcc'.  It
  629. might become possible in the future to supply a different dependency
  630. generating program, if there is enough demand.
  631.  
  632.    This mode is enabled by default if any C program or library is
  633. defined in the current directory.
  634.  
  635.    When you decide to make a distribution, the `dist' target will
  636. re-run `automake' with the `--include-deps' option.  This causes the
  637. previously generated dependencies to be inserted into the generated
  638. `Makefile.in', and thus into the distribution.  `--include-deps' also
  639. turns off inclusion of the dependency generation code.
  640.  
  641.    This mode can be suppressed by putting `no-dependencies' in the
  642. variable `AUTOMAKE_OPTIONS'.
  643.  
  644. 
  645. File: automake.info,  Node: Other objects,  Next: Documentation,  Prev: Programs,  Up: Top
  646.  
  647. Other Derived Objects
  648. *********************
  649.  
  650.    Automake can handle derived objects which are not C programs.
  651. Sometimes the support for actually building such objects must be
  652. explicitly supplied, but Automake will still automatically handle
  653. installation and distribution.
  654.  
  655. * Menu:
  656.  
  657. * Scripts::                     Executable scripts
  658. * Headers::                     Header files
  659. * Data::                        Architecture-independent data files
  660. * Sources::                     Derived sources
  661.  
  662. 
  663. File: automake.info,  Node: Scripts,  Next: Headers,  Up: Other objects
  664.  
  665. Executable Scripts
  666. ==================
  667.  
  668.    It is possible to define and install programs which are scripts.
  669. Such programs are listed using the `SCRIPTS' primary name.  `automake'
  670. doesn't define any dependencies for scripts; the `Makefile.am' should
  671. include the appropriate rules.
  672.  
  673.    `automake' does not assume that scripts are derived objects; such
  674. objects are must be deleted by hand; see *Note Clean:: for more
  675. information.
  676.  
  677.    `automake' itself is a script that is generated at configure time
  678. from `automake.in'.  Here is how this is handled:
  679.  
  680.      bin_SCRIPTS = automake
  681.  
  682.    Since `automake' appears in the `AC_OUTPUT' macro, dependencies for
  683. it are automatically generated.
  684.  
  685.    Script objects can be installed in `bindir', `sbindir',
  686. `libexecdir', or `pkgdatadir'.
  687.  
  688. 
  689. File: automake.info,  Node: Headers,  Next: Data,  Prev: Scripts,  Up: Other objects
  690.  
  691. Header files
  692. ============
  693.  
  694.    Header files are specified by the `HEADERS' family of variables.
  695. Generally header files are not installed, so the `noinst_HEADERS'
  696. variable will be the most used.
  697.  
  698.    All header files must be listed somewhere; missing ones will not
  699. appear in the distribution.  Often it is most convenient to list
  700. uninstalled headers with the rest of the sources for a program.  *Note
  701. A Program::.
  702.  
  703.    Headers can be installed in `includedir', `oldincludedir', or
  704. `pkgincludedir'.
  705.  
  706. 
  707. File: automake.info,  Node: Data,  Next: Sources,  Prev: Headers,  Up: Other objects
  708.  
  709. Architecture-independent data files
  710. ===================================
  711.  
  712.    Automake supports the installation of miscellaneous data files using
  713. the `DATA' family of variables.
  714.  
  715.    Such data can be installed in the directories `datadir',
  716. `sysconfdir', `sharedstatedir', `localstatedir', or `pkgdatadir'.
  717.  
  718.    All such data files are included in the distribution.
  719.  
  720.    Here is how `autoconf' installs its auxiliary data files:
  721.  
  722.      pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
  723.      compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
  724.      dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
  725.      libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
  726.      mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
  727.      remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
  728.      texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed
  729.  
  730. 
  731. File: automake.info,  Node: Sources,  Prev: Data,  Up: Other objects
  732.  
  733. Built sources
  734. =============
  735.  
  736.    Occasionally a file which would otherwise be called "source" (eg a C
  737. `.h' file) is actually derived from some other file.  Such files should
  738. be listed in the `BUILT_SOURCES' variable.
  739.  
  740.    Files listed in `BUILT_SOURCES' are built before any automatic
  741. dependency tracking is done.  Built sources are included in a
  742. distribution.
  743.  
  744. 
  745. File: automake.info,  Node: Documentation,  Next: Install,  Prev: Other objects,  Up: Top
  746.  
  747. Building documentation
  748. **********************
  749.  
  750.    Currently Automake provides support for Texinfo and man pages.
  751.  
  752. * Menu:
  753.  
  754. * Texinfo::                     Texinfo
  755. * Man pages::                   Man pages
  756.  
  757. 
  758. File: automake.info,  Node: Texinfo,  Next: Man pages,  Up: Documentation
  759.  
  760. Texinfo
  761. =======
  762.  
  763.    If the current directory contains Texinfo source, you must declare it
  764. with the `TEXINFOS' primary.  Generally Texinfo files are converted
  765. into info, and thus the `info_TEXINFOS' macro is most commonly used
  766. here.  Note that any Texinfo source file must end in the `.texi'
  767. extension (`.texinfo' won't work).
  768.  
  769.    If the `.texi' file `@include's `version.texi', then that file will
  770. be automatically generated.  `version.texi' defines three Texinfo
  771. macros you can reference: `EDITION', `VERSION', and `UPDATED'.  The
  772. first two hold the version number of your package (but are kept
  773. separate for clarity); the last is the date the primary file was last
  774. modified.  The `version.texi' support requires the `mdate-sh' program;
  775. this program is supplied with Automake.
  776.  
  777.    Sometimes an info file actually depends on more than one `.texi'
  778. file.  For instance, in the `xdvik' distribution, `kpathsea.texi'
  779. includes the files `install.texi', `copying.texi', and `freedom.texi'.
  780. You can tell Automake about these dependencies using the
  781. `texi_TEXINFOS' variable.  Here is how `xdvik' could do it:
  782.  
  783.      info_TEXINFOS = kpathsea.texi
  784.      kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
  785.  
  786.    Automake will warn if a directory containing Texinfo source does not
  787. also contain the file `texinfo.tex'.  This file is supplied with
  788. Automake.
  789.  
  790.    Automake generates an `install-info' target; some people apparently
  791. use this.
  792.  
  793. 
  794. File: automake.info,  Node: Man pages,  Prev: Texinfo,  Up: Documentation
  795.  
  796. Man pages
  797. =========
  798.  
  799.    A package can also include man pages.  (Though see the GNU standards
  800. on this matter, *Note Man Pages: (standards.info)Man Pages.)  Man pages
  801. are declared using the `MANS' primary.  Generally the `man_MANS' macro
  802. is used.  Man pages are automatically installed in the correct
  803. subdirectory of `mandir', based on the file extension.
  804.  
  805.    By default, man pages are installed by `make install'.  However,
  806. since the GNU project does not require man pages, many maintainers do
  807. not expend effort to keep the man pages up to date.  In these cases, the
  808. `no-installman' option will prevent the man pages from being installed
  809. by default.  The user can still explicitly install them via `make
  810. install-man'.
  811.  
  812.    Here is how the documentation is handled in GNU `cpio' (which
  813. includes both Texinfo documentation and man pages):
  814.  
  815.      info_TEXINFOS = cpio.texi
  816.      man_MANS = cpio.1 mt.1
  817.  
  818.    Texinfo source, info pages and man pages are all considered to be
  819. source for the purposes of making a distribution.
  820.  
  821. 
  822. File: automake.info,  Node: Install,  Next: Clean,  Prev: Documentation,  Up: Top
  823.  
  824. What Gets Installed
  825. *******************
  826.  
  827.    Naturally, Automake handles the details of actually installing your
  828. program once it has been built.  All `PROGRAMS', `SCRIPTS',
  829. `LIBRARIES', `DATA' and `HEADERS' are automatically installed in the
  830. appropriate places.
  831.  
  832.    Automake also handles installing any specified info and man pages.
  833.  
  834.    Automake generates separate `install-data' and `install-exec'
  835. targets, in case the installer is installing on multiple machines which
  836. share directory structure - these targets allow the machine-independent
  837. parts to be installed only once.  The `install' target depends on both
  838. of these targets.
  839.  
  840.    Automake also generates an `uninstall' target, and an `installdirs'
  841. target.
  842.  
  843.    It is possible to extend this mechanism by defining an
  844. `install-exec-local' or `install-data-local' target.  If these targets
  845. exist, they will be run at `make install' time.
  846.  
  847. 
  848. File: automake.info,  Node: Clean,  Next: Dist,  Prev: Install,  Up: Top
  849.  
  850. What Gets Cleaned
  851. *****************
  852.  
  853.    The GNU Makefile Standards specify a number of different clean rules.
  854. Generally the files that can cleaned are determined automatically by
  855. Automake.  Of course, Automake also recognizes some variables that can
  856. be defined to specify additional files to clean.  These variables are
  857. `MOSTLYCLEANFILES', `CLEANFILES', `DISTCLEANFILES', and
  858. `MAINTAINERCLEANFILES'.
  859.  
  860.    In Automake, the `automake' program is not automatically removed,
  861. because it is an executable script.  So this code in `Makefile.am'
  862. causes it to be removed by `make clean':
  863.  
  864.      CLEANFILES = automake
  865.  
  866. 
  867. File: automake.info,  Node: Dist,  Next: Tests,  Prev: Clean,  Up: Top
  868.  
  869. What Goes in a Distribution
  870. ***************************
  871.  
  872.    The `dist' target in the generated `Makefile.in' can be used to
  873. generate a gzip'd `tar' file for distribution.  The tar file is named
  874. based on the PACKAGE and VERSION variables.
  875.  
  876.    For the most part, the files to distribute are automatically found by
  877. Automake: all source files are automatically included in a distribution,
  878. as are all `Makefile.am's and `Makefile.in's.  Automake also has a
  879. built-in list of commonly used files which, if present in the current
  880. directory, are automatically included.  This list is printed by
  881. `automake --help'.  Also, files which are read by `configure' (ie, the
  882. source files corresponding to the files specified in the `AC_OUTPUT'
  883. invocation) are automatically distributed.
  884.  
  885.    Still, sometimes there are files which must be distributed, but which
  886. are not covered in the automatic rules.  These files should be listed in
  887. the `EXTRA_DIST' variable.
  888.  
  889.    Occasionally it is useful to be able to change the distribution
  890. before it is packaged up.  If the `dist-hook' target exists, it is run
  891. after the distribution directory is filled, but before the actual tar
  892. (or shar) file is created.  One way to use this is for distributing file
  893. in subdirectories for which a new `Makefile.am' is overkill:
  894.  
  895.      dist-hook:
  896.              mkdir $(distdir)/random
  897.              cp -p random/a1 random/a2 $(distdir)/random
  898.  
  899.    Automake also generates a `distcheck' target which can be help to
  900. ensure that a given distribution will actually work.  `distcheck' makes
  901. a distribution, and then tries to do a `VPATH' build.
  902.  
  903. 
  904. File: automake.info,  Node: Tests,  Next: Options,  Prev: Dist,  Up: Top
  905.  
  906. Support for test suites
  907. ***********************
  908.  
  909.    Automake supports a two forms of test suite.
  910.  
  911.    If the variable `TESTS' is defined, its value is taken to be a list
  912. of programs to run in order to do the testing.  The programs can either
  913. be derived objects or source objects; the generated rule will look both
  914. in SRCDIR and `.'.  The number of failures will be printed at the end
  915. of the run.
  916.  
  917.    If `dejagnu' appears in `AUTOMAKE_OPTIONS', then the a
  918. `dejagnu'-based test suite is assumed.  The value of the variable
  919. `DEJATOOL' is passed as the `--tool' argument to `runtest'; it defaults
  920. to the name of the package.  The variables `EXPECT', `RUNTEST' and
  921. `RUNTESTFLAGS' can also be overridden to provide project-specific
  922. values.  For instance, you will need to do this if you are testing a
  923. compiler toolchain, because the default values do not take into account
  924. host and target names.
  925.  
  926.    In either case, the testing is done via `make check'.
  927.  
  928. 
  929. File: automake.info,  Node: Options,  Next: Miscellaneous,  Prev: Tests,  Up: Top
  930.  
  931. Changing Automake's Behavior
  932. ****************************
  933.  
  934.    Various features of Automake can be controlled by options in the
  935. `Makefile.am'.  Such options are listed in a special variable named
  936. `AUTOMAKE_OPTIONS'.  Currently understood options are:
  937.  
  938. `gnits'
  939. `gnu'
  940. `foreign'
  941.      The same as the corresponding `--strictness' option.
  942.  
  943. `no-installman'
  944.      The generated `Makefile.in' will not cause man pages to be
  945.      installed by default.  However, an `install-man' target will still
  946.      be available for optional installation.
  947.  
  948. `ansi2knr'
  949.      Turn on automatic de-ANSI-fication.
  950.  
  951. `dist-shar'
  952.      Generate a `dist-shar' target as well as the ordinary `dist'
  953.      target.
  954.  
  955. `dist-zip'
  956.      Generate a `dist-zip' target as well as the ordinary `dist' target.
  957.  
  958. `no-dependencies'
  959.      This is similar to using `--include-deps' on the command line, but
  960.      is useful for those situations where you don't have the necessary
  961.      bits to make automatic dependency tracking work *Note
  962.      Dependencies::.  In this case the effect is to effectively disable
  963.      automatic dependency tracking.
  964.  
  965. VERSION
  966.      A version number (eg `0.30') can be specified.  If Automake is not
  967.      newer than the version specified, creation of the `Makefile.in'
  968.      will be suppressed.
  969.  
  970.    Unrecognized options are diagnosed by `automake'.
  971.  
  972. 
  973. File: automake.info,  Node: Miscellaneous,  Next: Extending,  Prev: Options,  Up: Top
  974.  
  975. Miscellaneous Rules
  976. *******************
  977.  
  978.    There are a few rules and variables that didn't fit anywhere else.
  979.  
  980. * Menu:
  981.  
  982. * Tags::                        Interfacing to etags and mkid
  983. * Suffixes::                    Handling new file extensions
  984. * Built::                       Built sources
  985.  
  986. 
  987. File: automake.info,  Node: Tags,  Next: Suffixes,  Up: Miscellaneous
  988.  
  989. Interfacing to `etags'
  990. ======================
  991.  
  992.    `automake' will generate rules to generate `TAGS' files for use with
  993. GNU Emacs under some circumstances.
  994.  
  995.    If any C source code or headers are present, then a `tags' target
  996. will be generated for the directory.
  997.  
  998.    At the topmost directory of a multi-directory package, a `tags'
  999. target file will be generated which, when run, will generate a `TAGS'
  1000. file that includes by reference all `TAGS' files from subdirectories.
  1001.  
  1002.    Also, if the variable `ETAGS_ARGS' is defined, a `tags' target will
  1003. be generated.  This variable is intended for use in directories which
  1004. contain taggable source that `etags' does not understand.
  1005.  
  1006.    Here is how Automake generates tags for its source, and for nodes in
  1007. its Texinfo file:
  1008.  
  1009.      ETAGS_ARGS = automake.in --lang=none \
  1010.       --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi
  1011.  
  1012.    Automake will also generate an `ID' target which will run `mkid' on
  1013. the source.  This is only supported on a directory-by-directory basis.
  1014.  
  1015. 
  1016. File: automake.info,  Node: Suffixes,  Next: Built,  Prev: Tags,  Up: Miscellaneous
  1017.  
  1018. Handling new file extensions
  1019. ============================
  1020.  
  1021.    It is sometimes useful to introduce a new implicit rule to handle a
  1022. file type that Automake does not know about.  If this is done, you must
  1023. notify GNU Make of the new suffixes.  This can be done by putting a list
  1024. of new suffixes in the `SUFFIXES' variable.
  1025.  
  1026. 
  1027. File: automake.info,  Node: Built,  Prev: Suffixes,  Up: Miscellaneous
  1028.  
  1029. Built sources
  1030. =============
  1031.  
  1032.    FIXME write this
  1033.  
  1034. 
  1035. File: automake.info,  Node: Extending,  Next: Distributing,  Prev: Miscellaneous,  Up: Top
  1036.  
  1037. When Automake Isn't Enough
  1038. **************************
  1039.  
  1040.    Sometimes `automake' isn't enough.  Then you just lose.
  1041.  
  1042.    Actually, `automake's implicit copying semantics means that many
  1043. problems can be worked around by simply adding some `make' targets and
  1044. rules to `Makefile.in'.  `automake' will ignore these additions.
  1045.  
  1046.    There are some caveats to doing this.  Although you can overload a
  1047. target already used by `automake', it is often inadvisable,
  1048. particularly in the topmost directory of a non-flat package.  However,
  1049. various useful targets have a `-local' version you can specify in your
  1050. `Makefile.in'.  Automake will supplement the standard target with these
  1051. user-supplied targets.
  1052.  
  1053.    The targets that support a local version are `all', `info', `dvi',
  1054. `check', `install-data', `install-exec', and `uninstall'.
  1055.  
  1056.    For instance, here is how to install a file in `/etc':
  1057.  
  1058.      install-data-local:
  1059.              $(INSTALL_DATA) $(srcdir)/afile /etc/afile
  1060.  
  1061.    Some targets also have a way to run another target, called a "hook",
  1062. after their work is done.  The hook is named after the principal target,
  1063. with `-hook' appended.  The targets allowing hooks are `install-data',
  1064. `install-exec', and `dist'.
  1065.  
  1066.    For instance, here is how to create a hard link to an installed
  1067. program:
  1068.  
  1069.      install-exec-hook:
  1070.              $(LN) $(bindir)/program $(bindir)/proglink
  1071.  
  1072. 
  1073. File: automake.info,  Node: Distributing,  Next: Examples,  Prev: Extending,  Up: Top
  1074.  
  1075. Distributing `Makefile.in's
  1076. ***************************
  1077.  
  1078.    Automake places no restrictions on the distribution of the resulting
  1079. `Makefile.in's.  We still encourage software authors to distribute
  1080. their work under terms like those of the GPL, but doing so is not
  1081. required to use Automake.
  1082.  
  1083.    Some of the files that can be automatically installed via the
  1084. `--add-missing' switch do fall under the GPL; examine each file to see.
  1085.  
  1086. 
  1087. File: automake.info,  Node: Examples,  Next: Future,  Prev: Distributing,  Up: Top
  1088.  
  1089. Some example packages
  1090. *********************
  1091.  
  1092.    Here are some examples of how Automake can be used.
  1093.  
  1094. * Menu:
  1095.  
  1096. * Hello::                       The simplest GNU program
  1097. * Tricky::                      A trickier example
  1098. * Automake::                    Automake's own use
  1099. * Textutils::                   A deep hierarchy
  1100.  
  1101. 
  1102. File: automake.info,  Node: Hello,  Next: Tricky,  Up: Examples
  1103.  
  1104. The simplest GNU program
  1105. ========================
  1106.  
  1107.    `hello' is renowned for its classic simplicity and versatility.
  1108. What better place to begin a tour?  The below shows what could be used
  1109. as the Hello distribution's `Makefile.am'.
  1110.  
  1111.      bin_PROGRAMS = hello
  1112.      hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h
  1113.      hello_LDADD = @ALLOCA@
  1114.      info_TEXINFOS = hello.texi
  1115.      hello_TEXINFOS = gpl.texi
  1116.      
  1117.      EXTRA_DIST = testdata
  1118.      
  1119.      check-local: hello
  1120.              @echo expect no output from diff
  1121.              ./hello > test.out
  1122.              diff -c $(srcdir)/testdata test.out
  1123.              rm -f test.out
  1124.  
  1125.    Of course, Automake also requires some minor changes to
  1126. `configure.in'.  The new `configure.in' would read:
  1127.  
  1128.      dnl Process this file with autoconf to produce a configure script.
  1129.      AC_INIT(hello.c)
  1130.      VERSION=1.3
  1131.      AC_SUBST(VERSION)
  1132.      PACKAGE=hello
  1133.      AC_SUBST(PACKAGE)
  1134.      AC_PROG_CC
  1135.      AC_PROG_CPP
  1136.      AC_PROG_INSTALL
  1137.      AC_STDC_HEADERS
  1138.      AC_HAVE_HEADERS(string.h fcntl.h sys/file.h)
  1139.      AC_ALLOCA
  1140.      AC_OUTPUT(Makefile)
  1141.  
  1142.    If Hello were really going to use Automake, the `version.c' file
  1143. would probably be deleted, or changed so as to be automatically
  1144. generated.
  1145.  
  1146. 
  1147. File: automake.info,  Node: Tricky,  Next: Automake,  Prev: Hello,  Up: Examples
  1148.  
  1149. A tricker example
  1150. =================
  1151.  
  1152.    Here is another, trickier example.  It shows how to generate two
  1153. programs (`ctags' and `etags') from the same source file (`etags.c').
  1154. The difficult part is that each compilation of `etags.c' requires
  1155. different `cpp' flags.
  1156.  
  1157.      bin_PROGRAMS = etags ctags
  1158.      ctags_SOURCES =
  1159.      ctags_LDADD = ctags.o
  1160.      ctags_DEPENDENCIES = ctags.o
  1161.      
  1162.      etags.o:
  1163.              $(COMPILE) -DETAGS_REGEXPS etags.c
  1164.      
  1165.      ctags.o:
  1166.              $(COMPILE) -DCTAGS -o ctags.o etags.c
  1167.  
  1168.    Note that `ctags_SOURCES' is defined to be empty - that way no
  1169. implicit value is substituted.  The implicit value, however, is used to
  1170. generate `etags' from `etags.o'.
  1171.  
  1172.    `ctags_LDADD' is used to get `ctags.o' into the link line, while
  1173. `ctags_DEPENDENCIES' exists to make sure that `ctags.o' gets built in
  1174. the first place.
  1175.  
  1176.    This is a somewhat pathological example.
  1177.  
  1178. 
  1179. File: automake.info,  Node: Automake,  Next: Textutils,  Prev: Tricky,  Up: Examples
  1180.  
  1181. Automake uses itself
  1182. ====================
  1183.  
  1184.    Automake, of course, uses itself to generate its `Makefile.in'.
  1185. Since Automake is a shallow package, it has more than one
  1186. `Makefile.am'.  Here is the top-level `Makefile.am':
  1187.  
  1188.      ## Process this file with automake to create Makefile.in
  1189.      
  1190.      AUTOMAKE_OPTIONS = gnits
  1191.      MAINT_CHARSET = latin1
  1192.      PERL = @PERL@
  1193.      
  1194.      SUBDIRS = tests
  1195.      
  1196.      bin_SCRIPTS = automake
  1197.      info_TEXINFOS = automake.texi
  1198.      
  1199.      pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
  1200.      compile.am data.am depend.am \
  1201.      dist-vars.am footer.am header.am header-vars.am \
  1202.      kr-vars.am libraries-vars.am \
  1203.      libraries.am library.am mans-vars.am \
  1204.      program.am programs.am remake-hdr.am \
  1205.      remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
  1206.      tags-clean.am \
  1207.      texi-version.am texinfos-vars.am texinfos.am \
  1208.      libraries-clean.am programs-clean.am data-clean.am \
  1209.      COPYING INSTALL texinfo.tex \
  1210.      ansi2knr.c ansi2knr.1 \
  1211.      aclocal.m4
  1212.      
  1213.      ## These must all be executable when installed.
  1214.      pkgdata_SCRIPTS = config.guess config.sub install-sh mdate-sh mkinstalldirs
  1215.      
  1216.      CLEANFILES = automake
  1217.      
  1218.      # The following requires a fixed version of the Emacs 19.30 etags.
  1219.      ETAGS_ARGS = automake.in --lang=none \
  1220.       --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi
  1221.      
  1222.      ## `test -x' is not portable.  So we use Perl instead.  If Perl
  1223.      ## doesn't exist, then this test is meaningless anyway.
  1224.      # Check to make sure some installed files are executable.
  1225.      installcheck-local:
  1226.          $(PERL) -e "exit ! -x '$(pkgdatadir)/config.guess';"
  1227.          $(PERL) -e "exit ! -x '$(pkgdatadir)/config.sub';"
  1228.          $(PERL) -e "exit ! -x '$(pkgdatadir)/install-sh';"
  1229.          $(PERL) -e "exit ! -x '$(pkgdatadir)/mdate-sh';"
  1230.          $(PERL) -e "exit ! -x '$(pkgdatadir)/mkinstalldirs';"
  1231.      
  1232.      # Some simple checks:
  1233.      # * syntax check with perl4 and perl5.
  1234.      # * make sure the scripts don't use 'true'
  1235.      # * expect no instances of '${...}'
  1236.      # These are only really guaranteed to work on my machine.
  1237.      maintainer-check: automake check
  1238.          $(PERL) -c -w automake
  1239.          @if grep '^[^#].*true' $(srcdir)/[a-z]*.am; then \
  1240.            echo "can't use 'true' in GNU Makefile" 1>&2; \
  1241.            exit 1;                \
  1242.          else :; fi
  1243.          @if test `fgrep '$${' $(srcdir)/[a-z]*.am | wc -l` -ne 0; then \
  1244.            echo "found too many uses of '\$${'" 1>&2; \
  1245.            exit 1;                \
  1246.          fi
  1247.          if $(SHELL) -c 'perl4.036 -v' >/dev/null 2>&1; then \
  1248.            perl4.036 -c -w automake; \
  1249.          else :; fi
  1250.      
  1251.      # Tag before making distribution.  Also, don't make a distribution if
  1252.      # checks fail.  Also, make sure the NEWS file is up-to-date.
  1253.      cvs-dist: maintainer-check
  1254.          @if sed 1q NEWS | grep -e "$(VERSION)" > /dev/null; then :; else \
  1255.            echo "NEWS not updated; not releasing" 1>&2; \
  1256.            exit 1;                \
  1257.          fi
  1258.          cvs tag `echo "Release-$(VERSION)" | sed 's/\./-/g'`
  1259.          $(MAKE) dist
  1260.  
  1261.    As you can see, Automake defines many of its own rules, to make the
  1262. maintainer's job easier.  For instance the `cvs-dist' rule
  1263. automatically tags the current version in the CVS repository, and then
  1264. makes a standard distribution.
  1265.  
  1266.    Automake consists primarily of one program, `automake', and a number
  1267. of auxiliary scripts.  Automake also installs a number of programs
  1268. which are possibly installed via the `--add-missing' option; these
  1269. scripts are listed in the `pkgdata_SCRIPTS' variable.
  1270.  
  1271.    Automake also has a `tests' subdirectory, as indicated in the
  1272. `SUBDIRS' variable above.  Here is `tests/Makefile.am':
  1273.  
  1274.      ## Process this file with automake to create Makefile.in
  1275.      
  1276.      AUTOMAKE_OPTIONS = gnits
  1277.      
  1278.      TESTS = mdate.test vtexi.test acoutput.test instexec.test checkall.test \
  1279.      acoutnoq.test acouttbs.test libobj.test proginst.test acoutqnl.test \
  1280.      confincl.test spelling.test prefix.test badprog.test depend.test
  1281.      
  1282.      EXTRA_DIST = defs
  1283.  
  1284.    This is where all the tests are really run.  `defs' is an
  1285. initialization file used by each test script; it is explicitly mentioned
  1286. because `automake' has no way of automatically finding it.
  1287.  
  1288. 
  1289. File: automake.info,  Node: Textutils,  Prev: Automake,  Up: Examples
  1290.  
  1291. A deep hierarchy
  1292. ================
  1293.  
  1294.    The GNU textutils are a collection of programs for manipulating text
  1295. files.  They are distributed as a deep package.  The textutils have only
  1296. recently been modified to use Automake; the examples come from a
  1297. prerelease.
  1298.  
  1299.    Here is the top-level `Makefile.am':
  1300.  
  1301.      SUBDIRS = lib src doc man
  1302.  
  1303.    In the `lib' directory, a library is built which is used by each
  1304. textutil.  Here is `lib/Makefile.am':
  1305.  
  1306.      noinst_LIBRARIES = tu
  1307.      
  1308.      EXTRA_DIST = rx.c regex.c
  1309.      
  1310.      tu_SOURCES = error.h getline.h getopt.h linebuffer.h \
  1311.      long-options.h md5.h regex.h rx.h xstrtod.h xstrtol.h xstrtoul.h \
  1312.      error.c full-write.c getline.c getopt.c getopt1.c \
  1313.      linebuffer.c long-options.c md5.c memchr.c safe-read.c \
  1314.      xmalloc.c xstrtod.c xstrtol.c xstrtoul.c
  1315.      
  1316.      tu_LIBADD = @REGEXOBJ@ @LIBOBJS@ @ALLOCA@
  1317.  
  1318.    The `src' directory contains the source for all the textutils - 23
  1319. programs in all.  The `Makefile.am' for this directory also includes
  1320. some simple checking code, and constructs a `version.c' file on the fly:
  1321.  
  1322.      bin_PROGRAMS = cat cksum comm csplit cut expand fmt fold head join md5sum \
  1323.      nl od paste pr sort split sum tac tail tr unexpand uniq wc
  1324.      
  1325.      noinst_HEADERS = system.h version.h
  1326.      DISTCLEANFILES = stamp-v version.c
  1327.      
  1328.      INCLUDES = -I$(top_srcdir)/lib
  1329.      
  1330.      LDADD = version.o ../lib/libtu.a
  1331.      
  1332.      $(PROGRAMS): version.o ../lib/libtu.a
  1333.      
  1334.      AUTOMAKE_OPTIONS = ansi2knr
  1335.      
  1336.      version.c: stamp-v
  1337.      stamp-v: Makefile
  1338.          rm -f t-version.c
  1339.          echo '#include <config.h>' > t-version.c
  1340.          echo '#include "version.h"' >> t-version.c
  1341.          echo 'const char *version_string = "'GNU @PACKAGE@ @VERSION@'";' \
  1342.              >> t-version.c
  1343.          if cmp -s version.c t-version.c; then    \
  1344.            rm t-version.c;            \
  1345.          else                    \
  1346.            mv t-version.c version.c;        \
  1347.          fi
  1348.          echo timestamp > $@
  1349.      
  1350.      check: md5sum
  1351.          ./md5sum \
  1352.           --string="" \
  1353.           --string="a" \
  1354.           --string="abc" \
  1355.           --string="message digest" \
  1356.           --string="abcdefghijklmnopqrstuvwxyz" \
  1357.           --string="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" \
  1358.           --string="12345678901234567890123456789012345678901234567890123456789012345678901234567890" \
  1359.             | diff -c $(srcdir)/md5-test.rfc -
  1360.  
  1361.    The `doc' directory builds the info documentation for the textutils:
  1362.  
  1363.      info_TEXINFOS = textutils.texi
  1364.  
  1365.    And, last, the `man' directory installs the man pages for all the
  1366. textutils:
  1367.  
  1368.      man_MANS = cat.1 cksum.1 comm.1 csplit.1 cut.1 expand.1 fmt.1 fold.1 head.1 \
  1369.      join.1 md5sum.1 nl.1 od.1 paste.1 pr.1 sort.1 split.1 sum.1 tac.1 tail.1 \
  1370.      tr.1 unexpand.1 uniq.1 wc.1
  1371.  
  1372.    You can now see how easy it is to handle even a largish project using
  1373. Automake.
  1374.  
  1375. 
  1376. File: automake.info,  Node: Future,  Next: Variables,  Prev: Examples,  Up: Top
  1377.  
  1378. Some ideas for the future
  1379. *************************
  1380.  
  1381.    Here are some things that might happen in the future:
  1382.  
  1383.    * HTML support.
  1384.  
  1385.    * The output will be cleaned up.  For instance, only variables which
  1386.      are actually used will appear in the generated `Makefile.in'.
  1387.  
  1388.    * There will be support for automatically recoding a distribution.
  1389.      The intent is to allow a maintainer to use whatever character set
  1390.      is most convenient locally, but for all distributions to be
  1391.      Unicode or ISO 10646 with the UTF-8 encoding.
  1392.  
  1393. 
  1394. File: automake.info,  Node: Variables,  Next: Configure variables,  Prev: Future,  Up: Top
  1395.  
  1396. Index of Variables
  1397. ******************
  1398.  
  1399. * Menu:
  1400.  
  1401. * AUTOMAKE_OPTIONS:                     Options.
  1402. * AUTOMAKE_OPTIONS:                     Dependencies.
  1403. * AUTOMAKE_OPTIONS:                     ANSI.
  1404. * BUILT_SOURCES:                        Sources.
  1405. * CLEANFILES:                           Clean.
  1406. * DATA:                                 Data.
  1407. * DATA:                                 Generalities.
  1408. * DEJATOOL:                             Tests.
  1409. * DISTCLEANFILES:                       Clean.
  1410. * EXPECT:                               Tests.
  1411. * EXTRA_DIST:                           Dist.
  1412. * EXTRA_PROGRAMS:                       A Program.
  1413. * HEADERS:                              Headers.
  1414. * HEADERS:                              Generalities.
  1415. * info_TEXINFOS:                        Texinfo.
  1416. * LDADD:                                A Program.
  1417. * LIBADD:                               A Library.
  1418. * LIBRARIES:                            Generalities.
  1419. * MAINTAINERCLEANFILES:                 Clean.
  1420. * MANS:                                 Man pages.
  1421. * MANS:                                 Generalities.
  1422. * man_MANS:                             Man pages.
  1423. * MOSTLYCLEANFILES:                     Clean.
  1424. * PROGRAMS:                             Generalities.
  1425. * PROGRAMS:                             Generalities.
  1426. * RUNTEST:                              Tests.
  1427. * RUNTESTFLAGS:                         Tests.
  1428. * SCRIPTS:                              Scripts.
  1429. * SCRIPTS:                              Generalities.
  1430. * SOURCES:                              A Program.
  1431. * SUBDIRS:                              Top level.
  1432. * SUBDIRS:                              Generalities.
  1433. * SUFFIXES:                             Suffixes.
  1434. * TEXINFOS:                             Texinfo.
  1435. * TEXINFOS:                             Texinfo.
  1436. * TEXINFOS:                             Generalities.
  1437. * _LDADD:                               A Program.
  1438. * _LIBADD:                              A Library.
  1439. * _SOURCES:                             A Program.
  1440. * _TEXINFOS:                            Texinfo.
  1441.  
  1442. 
  1443. File: automake.info,  Node: Configure variables,  Next: Targets,  Prev: Variables,  Up: Top
  1444.  
  1445. Index of Configure Variables and Macros
  1446. ***************************************
  1447.  
  1448. * Menu:
  1449.  
  1450. * AC_ARG_PROGRAM:                       configure.
  1451. * AC_CANONICAL_HOST:                    configure.
  1452. * AC_CANONICAL_SYSTEM:                  configure.
  1453. * AC_CHECK_TOOL:                        configure.
  1454. * AC_CONFIG_AUX_DIR:                    configure.
  1455. * AC_CONFIG_HEADER:                     configure.
  1456. * AC_FUNC_ALLOCA:                       configure.
  1457. * AC_FUNC_FNMATCH:                      configure.
  1458. * AC_FUNC_GETLOADAVG:                   configure.
  1459. * AC_FUNC_MEMCMP:                       configure.
  1460. * AC_OUTPUT:                            configure.
  1461. * AC_PATH_XTRA:                         configure.
  1462. * AC_PROG_INSTALL:                      configure.
  1463. * AC_PROG_LIBTOOL:                      configure.
  1464. * AC_PROG_MAKE_SET:                     configure.
  1465. * AC_PROG_RANLIB:                       configure.
  1466. * AC_REPLACE_FUNCS:                     configure.
  1467. * AC_REPLACE_GNU_GETOPT:                configure.
  1468. * AC_STRUCT_ST_BLOCKS:                  configure.
  1469. * ALL_LINGUAS:                          configure.
  1470. * fp_C_PROTOTYPES:                      ANSI.
  1471. * fp_C_PROTOTYPES:                      configure.
  1472. * fp_FUNC_FNMATCH:                      configure.
  1473. * fp_PROG_INSTALL:                      configure.
  1474. * gm_PROG_LIBTOOL:                      configure.
  1475. * jm_MAINTAINER_MODE:                   configure.
  1476. * LIBOBJS:                              configure.
  1477. * PACKAGE:                              Dist.
  1478. * PACKAGE:                              configure.
  1479. * PACKAGE:                              Generalities.
  1480. * ud_GNU_GETTEXT:                       configure.
  1481. * VERSION:                              Dist.
  1482. * VERSION:                              configure.
  1483.  
  1484. 
  1485. File: automake.info,  Node: Targets,  Prev: Configure variables,  Up: Top
  1486.  
  1487. Index of Targets
  1488. ****************
  1489.  
  1490. * Menu:
  1491.  
  1492. * all:                                  Extending.
  1493. * check:                                Extending.
  1494. * dist:                                 Dist.
  1495. * dist:                                 Dependencies.
  1496. * dist-hook:                            Extending.
  1497. * dist-shar:                            Options.
  1498. * dist-zip:                             Options.
  1499. * distcheck:                            Dist.
  1500. * dvi:                                  Extending.
  1501. * id:                                   Tags.
  1502. * info:                                 Extending.
  1503. * install:                              Install.
  1504. * install-data:                         Extending.
  1505. * install-data:                         Install.
  1506. * install-data-hook:                    Extending.
  1507. * install-data-local:                   Install.
  1508. * install-exec:                         Extending.
  1509. * install-exec:                         Install.
  1510. * install-exec-hook:                    Extending.
  1511. * install-exec-local:                   Install.
  1512. * install-man:                          Options.
  1513. * install-man:                          Man pages.
  1514. * installdirs:                          Install.
  1515. * tags:                                 Tags.
  1516. * uninstall:                            Extending.
  1517. * uninstall:                            Install.
  1518.  
  1519.  
  1520. 
  1521. Tag Table:
  1522. Node: Top939
  1523. Node: Introduction2376
  1524. Node: Invoking Automake3812
  1525. Node: Generalities6395
  1526. Node: configure12609
  1527. Node: Top level16779
  1528. Node: Programs17950
  1529. Node: A Program18449
  1530. Node: A Library22145
  1531. Node: ANSI23508
  1532. Node: Dependencies24388
  1533. Node: Other objects25510
  1534. Node: Scripts26099
  1535. Node: Headers26945
  1536. Node: Data27528
  1537. Node: Sources28557
  1538. Node: Documentation28989
  1539. Node: Texinfo29288
  1540. Node: Man pages30796
  1541. Node: Install31889
  1542. Node: Clean32864
  1543. Node: Dist33547
  1544. Node: Tests35215
  1545. Node: Options36239
  1546. Node: Miscellaneous37644
  1547. Node: Tags38024
  1548. Node: Suffixes39104
  1549. Node: Built39511
  1550. Node: Extending39635
  1551. Node: Distributing41090
  1552. Node: Examples41606
  1553. Node: Hello42011
  1554. Node: Tricky43312
  1555. Node: Automake44288
  1556. Node: Textutils48581
  1557. Node: Future51458
  1558. Node: Variables52070
  1559. Node: Configure variables54219
  1560. Node: Targets56076
  1561. 
  1562. End Tag Table
  1563.